Handling Media Sample References1

You could always use GetMediaSampleReference to access samples in a movie one at a time. QuickTime 2.1 introduced GetMediaSampleReferences (note that this is the plural form of the GetMediaSampleReference function), which you can use to obtain information about groups of samples. QuickTime 2.1 also introduced AddMediaSampleReferences , which you can use to work with groups of samples that have already been added to a movie.

GetMediaSampleReferences

The GetMediaSampleReferences function allows your application to obtain reference information about groups of samples that are stored in a movie.



 
pascal OSErr GetMediaSampleReferences (

                     Media theMedia, 

                     TimeValue time, 

                     TimeValue *sampleTime, 

                     SampleDescriptionHandle sampleDescriptionH, 

                     long *sampleDescriptionIndex, 

                     long maxNumberOfEntries, 

                     long *actualNumberofEntries, 

                     SampleReferencePtr sampleRefs);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such toolbox functions as NewTrackMedia and GetTrackMedia . For information about these functions, see Inside Macintosh: QuickTime.
time: Specifies the starting time of the sample references to be retrieved. You must specify this value in the media's time scale.
sampleTime: Contains a pointer to a time value. The GetMediaSampleReferences function updates this time value to indicate the actual time of the first returned sample data. If you are not interested in this information, set this parameter to nil .
sampleDescriptionH: Contains a handle to a sample description. The GetMediaSampleReference function returns the sample description corresponding to the returned sample data. The function resizes this handle as appropriate. If you do not want the sample description, set this parameter to nil .; GetMediaSampleReferences only returns a single sample description. If the sample description changes within the media, GetMediaSampleReferences returns only as many samples as use a single sample description. You must call it again to get the next group of samples using the next sample description.
sampleDescriptionIndex: Contains a pointer to a long integer. The GetMediaSampleReferences function returns an index value to the sample descriptions that correspond to the returned sample data. You can use this index to retrieve the media sample descriptions with the GetMediaSampleDescription function. If you do not want this information, set this parameter to nil .
maxNumberOfEntries: Specifies the maximum number of entries to be returned. The sample references pointer provided by the sampleRefs parameter must be large enough to receive the number of entries specified by this parameter. The toolbox does not return more entries than you specify with this parameter. It may, however, return fewer.
actualNumberOfEntries: Contains a pointer to a long integer. The GetMediaSampleReferences function updates the field referred to by this parameter with the number of entries referred to by the returned reference.
sampleRefs: Contains a pointer to the number of SampleReferenceRecords specified in the maxNumberOfEntries parameter. On return from this call, the number of sample reference records indicated by the value returned in actualNumberOfEntries will be filled in.

Description

Using this function instead of GetMediaSampleReference can greatly increase the performance of operations that need access to information about each sample in a movie. No information is returned from this call that wasn't previously available from GetMediaSampleReference .

RESULT CODES

invalidMedia -2008 This media is corrupted or invalid.

Memory Manager errors

AddMediaSampleReferences

The AddMediaSampleReferences function allows your application to add groups of samples to a movie data file.



 
pascal OSErr AddMediaSampleReferences (

                     Media theMedia,

                     SampleDescriptionHandle sampleDescriptionH,

                     long numberOfSamples,

                     SampleReferencePtr sampleRefs,

                     TimeValue *sampleTime);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such toolbox functions as NewTrackMedia and GetTrackMedia . For information about these functions, see Inside Macintosh: QuickTime.
sampleDescriptionH: Contains a handle to a sample description. Some media structures may require sample descriptions. There are different sample descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an image description. A media that contains sound requires that you supply a sound description structure. For information about the Image Compression Manager and the sound description structure, see Inside Macintosh: QuickTime.; If you do not want the sample description, set this parameter to nil .
numberOfSamples: Specifies the number of samples contained in the reference. For details, see the AddMediaSample function description in Inside Macintosh: QuickTime.
sampleRefs: Contains a pointer to the number of SampleReferenceRecords specified in the numberOfSamples parameter.
sampleTime: Contains a pointer to a time value. After adding the reference to the media, the AddMediaSampleReferences function returns the time where the reference was inserted, using the time scale referred to by this parameter. If you do not want to receive this information, set this parameter to nil .

DISCUSSION

Using this function instead of AddMediaSampleReference can greatly improve the performance of operations that involve adding a large number of samples to a movie at one time. AddMediaSampleReferences provides no capabilities that weren't previously available with AddMediaSampleReference .

RESULT CODES

invalidMedia -2008 This media is corrupted or invalid.

Memory Manager errors